<html>
<head>
<title>OAuth 1.0 RC Revision 87</title>
</head>
<body>
<h1>OAuth 1.0 Draft Revision 87</h1>

<h2>Authors</h2>

<ul>
<li><span class="vcard"><span class="fn">Mark Atwood</span> (<span class="email">me@mark.atwood.name</span>)</span></li>
<li><span class="vcard"><span class="fn">Blaine Cook</span> (<span class="email">blaine@twitter.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Leah Culver</span> (<span class="email">leah@pownce.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Kellan Elliott-McCrea</span> (<span class="email">kellan@flickr.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Larry Halff</span> (<span class="email">larry@ma.gnolia.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Eran Hammer-Lahav</span> (<span class="email">eran@hueniverse.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Ben Laurie</span> (<span class="email">benl@google.com</span>)</span> </li>
<li><span class="vcard"><span class="fn">Chris Messina</span> (<span class="email">chris@citizenagency.com</span>)</span></li>
<li><span class="vcard"><span class="fn">John Panzer</span> (<span class="email">jpanzer@acm.org</span>)</span></li>
<li><span class="vcard"><span class="fn">David Recordon</span> (<span class="email">david@sixapart.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Eran Sandler</span> (<span class="email">eran@yedda.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Jonathan Sergent</span> (<span class="email">sergent@google.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Todd Sieling</span> (<span class="email">todd@ma.gnolia.com</span>)</span></li>
<li><span class="vcard"><span class="fn">Andy Smith</span> (<span class="email">andy@jaiku.com</span>)</span></li>
</ul>

<h2>Description</h2>

<p>The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring the User to disclose their Service Provider credentials to the Consumer. An example use case is allowing printing service print.example.com (the Consumer), to access private photos stored on photos.example.com (the Service Provider) without requiring the User to provide their photos.example.com credentials to print.example.com.</p>

<p>More generally, OAuth creates a freely-implementable and generic methodology for API authentication, benefitting developers who want their Consumer product to interact with various Service Providers.</p>

<p>While OAuth does not require a specific user interface or interaction pattern, recommendations and emerging best practices are described in this specification. Additionally, OAuth does not specify how Service Providers authenticate Users, making the protocol ideally suited for cases where authentication credentials are unavailable to the Consumer, such as with OpenID.</p>

<h2>Background</h2>

<p>OAuth aims to unify the experience and implementation of delegated web service authentication into a single, community-driven protocol. OAuth builds on existing protocols and best practices that have been independently implemented by various websites. An open standard, supported by large and small providers alike, promotes a consistent and trusted experience for both application developers and the users of those applications.</p>

<h2>Notation and Conventions</h2>

<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.</p>

<h2>Definitions</h2>

<ul>
<li>Service Provider
: A web application that allows access via OAuth. </li>
<li>User
: An individual who has an account with the Service Provider. </li>
<li>Consumer
: A website or application that uses OAuth to access the Service Provider on behalf of the User. </li>
<li>Consumer Developer
: An individual or organization that implements a Consumer. </li>
<li>Consumer Key
: A string used by the Consumer to identify itself to the Service Provider. </li>
<li>Consumer Secret
: A secret, specific to the Consumer Key, used by the Consumer to sign OAuth requests to the Service Provider.</li>
<li>Protected Resource(s)
: Data controlled by the Service Provider, which the Consumer can access through authentication.</li>
<li>Token
: A string used by the Consumer to gain access to the Protected Resource(s) on behalf of the User (instead of using the User's Service Provider credentials). There are two types of Tokens: Single-Use and Multi-Use.</li>
<li>Token Secret
: A secret, specific to a Token, which the Consumer uses to sign its OAuth requests to the Service Provider on behalf of a User.</li>
<li>Single-Use Token
: A Token generated by the Service Provider and given to the Consumer to identify the User in the authentication process. The Consumer MUST exchange the Single-Use Token for a Multi-Use Token after the User authenticates and grants access permission to the Consumer.</li>
<li>Multi-Use Token
: A Token generated by the Service Provider and given to the Consumer in order to identify the User in subsequent API requests. </li>
<li>Authorization Endpoint URL
: A URL provided by the Service Provider, that the Consumer uses to obtain authorization from the User for access to the Service Provider.</li>
<li>API Endpoint URL(s)
: URL(s) provided by the Service Provider, which the Consumer uses to make API requests, including obtaining Tokens.</li>
<li>Callback Endpoint URL
: A URL provided by a web Consumer, which the Service Provider uses to return a Single-Use Token and Token Secret.</li>
<li>Protocol Parameters
: Parameters with names beginning with <code>oauth_</code>.</li>
</ul>

<h2>Consumer Types</h2>

<p>Consumers are categorized based on their ability to:</p>

<ul>
<li>Accept incoming HTTP(S) requests.</li>
<li>Redirect the User (via web browser) to the Service Provider Authorization Endpoint URL.</li>
</ul>

<p>OAuth defines three Consumer types:</p>

<ul>
<li>Web-Based Consumer
: A website or other web-based application capable of accepting incoming HTTP(S) requests and User redirection.</li>
<li>Desktop Consumer
: An application running on a User computer capable of User redirection (directly or via a web browser installed on the User computer) but not accepting incoming HTTP(S) requests.</li>
<li>Manual-Token-Entry Consumer
: A Consumer incapable of making HTTP(S) redirections and incapable of accepting incoming HTTP(S) requests. Mobile devices and set-top boxes usually fall under this category.</li>
</ul>

<h2>Endpoint URLs</h2>

<p>All Endpoint URLs for both Service Providers and Consumers MUST include scheme, authority, and path, and MUST NOT include query or fragment as defined by RFC 3986 section 3. Service Providers MAY specify additional query parameters to be used with the Authorization and API Endpoint URLs, but those parameters are not considered part of the Endpoint URL.</p>

<h2>Setting Up to Use OAuth</h2>

<p>OAuth includes a Consumer Key and matching Consumer Secret that together authenticate the Consumer (as opposed to the User) to the Service Provider. Customer-specific identification allows the Service Provider to vary access levels to Consumers (such as un-throttled API access or other resources).</p>

<p>Only web-based Consumers are assumed to be capable of keeping their Consumer Secret private. Service Providers MUST NOT rely on the Consumer Secret as a method to verify the Consumer identity for non web-based Consumers.</p>

<h3>Service Providers</h3>

<p>Service Providers MUST enable Consumer Developers to obtain a Consumer Key and Consumer Secret. The process and requirements for provisioning these are entirely up to the Service Providers unless where otherwise specified.</p>

<p>The Consumer Secret MAY be either a randomized string or a public/private key pair. In the case that the Consumer Secret is a public/private key pair, the Service Provider only requires the public key, and SHOULD verify that the Consumer Developer is, in fact, the owner of the private key.</p>

<p>The Service Provider MUST also provide documentation to specify:</p>

<ol>
<li>The Authorization Endpoint URL and the API Endpoint URLs that the Consumer will use when making OAuth requests.</li>
<li>Signature algorithms supported by the Service Provider.</li>
<li>Any additional request parameters that the Service Provider requires in order to obtain a Token. Service Provider specific parameters MUST NOT begin with <code>oauth_</code>.</li>
</ol>

<h3>Consumers</h3>

<p>The Consumer Developer MUST establish a Consumer Key and a Consumer Secret with the Service Provider.</p>

<p>When registering a Consumer Key, the Consumer Developer MUST identify the Consumer type (web-based, desktop, or manual token entry). If the Consumer is web-based, the Consumer Developer MUST provide the Callback Endpoint URL where the Service Provider will send Tokens.</p>

<h2>HTTP Request Parameters</h2>

<p>Request parameter names and values are escaped using the RFC 3986 percent-encoding (%xx) mechanism. Characters not in the unreserved character set (RFC 3986 section 2.3) MUST be encoded. Characters in the unreserved character set MUST NOT be encoded. Hexadecimal characters in encodings MUST be upper case. Text names and values MUST be encoded as UTF-8 octets before percent-encoding them.</p>

<p>Protocol Parameters' names and values are case sensitive.</p>

<h2>Authenticating with OAuth</h2>

<p>OAuth Authentication is done in two broad steps. First, the Consumer MUST obtain a Single-Use Token from the Service Provider by having the User successfully sign into the Service Provider and grant access. Second, the Consumer MUST exchange the Single-Use Token for a Multi-Use Token which can be used to make API calls to Service Provider.</p>

<p>There are three variations to the first step of obtaining an authorized Single-Use Token. The variations are based on the Consumer type. The second step of exchanging a Single-Use Token for a Multi-Use Token is the same for all Consumer types. The following sections describe the process for obtaining Single-Use Tokens (for each Consumer type), and obtaining a Multi-Use Token. Each of these subsections is accompanied by a diagram showing the complete authentication process for the Consumer type.</p>

<h3>User Authentication and Consumer Access Grants</h3>

<p>OAuth does not specify how the Service Provider authenticates the User. However, it does provide a set of steps to verify User identity and obtain approval to grant the Consumer access to the Protected Resources.</p>

<ul>
<li>The Service Provider MUST first verify the User's identity before asking for consent. It MAY prompt the User to sign in if the User has not already done so.</li>
<li>The Service Provider presents to the User information about the Consumer requesting access (as registered by the Consumer Developer). The information MUST include the duration of the access and the Protected Resources provided. The information MAY include other details specific to the Service Provider.</li>
<li>The User MUST grant or decline permission for the Service Provider to give the Consumer access to the Protected Resources on behalf of the User. Permission MUST be granted for the protocol flow to continue. If the User denies the Consumer access, the Service Provider MUST NOT provide the Consumer with a Single-Use Token and MUST NOT allow access to the Protected Resources.</li>
</ul>

<h2>Obtaining a Single-Use Token</h2>

<h3>Web-based Consumer</h3>

<p>Web-based Consumers obtain a Single-Use Token by way of an HTTP Redirect from the Consumer to the Service Provider's Authorization Endpoint URL and back to the Consumer's Callback Endpoint URL, following these steps:</p>

<ol>
<li>The Consumer requests User authorization</li>
<li>The Service Provider authenticates the User and obtains User consent</li>
<li>The Service Provider issues a Single-Use Token</li>
</ol>

<p><img src="./diagrams/oauth_web_flow.png" alt="OAuth Web Flow Diagram" /></p>

<h4>1. The Consumer Requests User Authorization</h4>

<p>To request a Single-Use Token and Token Secret, the Consumer constructs an HTTP GET request to the Service Provider's Authorization Endpoint URL, to be sent via the User's web browser.</p>

<p>The request contains the following parameters:</p>

<ul>
<li><code>oauth_consumer_key</code>
: The Consumer Key.</li>
<li><code>oauth_state</code>
: An OPTIONAL parameter that will be passed through unmodified to the Consumer (this parameter SHOULD only be used in the case of stateless web-based Consumers).</li>
<li>Any additional parameters, as defined by the Service Provider.</li>
</ul>

<p>Once the request URL has been constructed the Consumer issues an HTTP 302 Redirect to the User's web-browser using that URL.</p>

<p>For example, if the Consumer is requesting a Single-Use Token from the Authorization Endpoint URL <code>https://sp.example.com/oauth/authorize</code> with the Consumer Key <code>0685bd91</code> the request would be:</p>

<pre><code>  https://sp.example.com/oauth/authorize?oauth_consumer_key=0685bd91
</code></pre>

<h4>2. The Service Provider Authenticates the User and Obtains Consent</h4>

<p>The Service Provider verifies the User's identity and asks for consent as detailed in the "User Authentication and Consumer Access Grants" section.</p>

<h4>3. The Service Provider issues a Single-Use Token</h4>

<p>After the User has authenticated with the Service Provider and has granted permission for Consumer access, the Service Provider will create a Single-Use Token and a corresponding Token Secret, and deliver it to the Consumer via an HTTP Redirect.</p>

<p>The response for a web-based Consumer includes the following GET parameters:</p>

<ul>
<li><code>oauth_token</code>
: The Single-Use Token.</li>
<li><code>oauth_token_secret</code>
: The Token Secret.</li>
<li><code>oauth_state</code>
: REQUIRED if one was provided in the Consumer request.</li>
</ul>

<p>For example, if the Service Provider has created a Single-Use Token <code>c3e347b6a5001c16</code> and Token Secret <code>678dfge7dghek243</code> for the Consumer, whose Callback Endpoint URL is <code>https://Consumer.example.com/validate</code>, then the Service Provider will redirect the User to the following URL:</p>

<pre><code>  https://Consumer.example.com/validate?oauth_token=c3e347b6a5001c16&amp;oauth_token_secret=678dfge7dghek243
</code></pre>

<h3>Desktop Consumers</h3>

<p>Desktop Consumers can redirect the User to the Service Provider but cannot accept incoming HTTP(S) requests from the Service Provider via a Callback Endpoint URL. Instead, they MUST first obtain a Single-Use Token.</p>

<ol>
<li>The Consumer requests a Single-Use Token</li>
<li>The Service Provider issues an unauthorized Single-Use Token</li>
<li>The Consumer redirects the User to the Service Provider</li>
<li>The Service Provider authenticates the User and obtains consent</li>
<li>The Service Provider directs the User back to the Consumer</li>
</ol>

<p><img src="./diagrams/oauth_desktop_flow.png" alt="Desktop Flow Diagram" /></p>

<h4>1. The Consumer Requests a Single-Use Token</h4>

<p>To obtain a Single-Use Token, the Consumer sends a request to the Service Provider's API Endpoint URL. The request contains the following parameters:</p>

<ul>
<li><code>oauth_consumer_key</code>
: The Consumer Key.</li>
<li><code>oauth_nonce</code>
: A one-time use value to verify the request has not been made before. See the "Request Nonce" section. </li>
<li><code>oauth_ts</code>
: An integer representing the time of request, expressed in number of seconds after January 1, 1970 00:00:00 GMT.</li>
<li><code>oauth_sigalg</code>
: The signature algorithm that the Consumer used to sign the request. </li>
<li><code>oauth_sig</code>
: The signature as defined in "Signing API Requests". </li>
</ul>

<p>For example, the Consumer has a Consumer Key <code>1b20acc6</code> and a Consumer Secret <code>427a5979d9df7722</code>. The Service Provider's API Endpoint URL for requesting a Single-Use Token is <code>http://sp.example.com/oauth/get_su_token</code>, and the request is using the HTTP GET method. The nonce is <code>17907867114999140772853922434221488511</code> and the timestamp of <code>1186953553</code>. Using <code>sha1</code> as the signature algorithm, the signature is then <code>26287279e66f7f183af02653e823625871167d16</code>, and the request is as follows:</p>

<pre><code>  https://sp.example.com/oauth/get_su_token?oauth_consumer_key=1b20acc6&amp;oauth_nonce=17907867114999140772853922434221488511&amp;oauth_ts=1186953553&amp;oauth_sigalg=sha1&amp;oauth_sig=26287279e66f7f183af02653e823625871167d16
</code></pre>

<h4>2. The Service Provider Issues an Unauthorized Single-Use Token</h4>

<p>The Service Provider generates a Single-Use Token and MUST ensure it cannot be exchanged for a Multi-Use Token until the User successfully grants access in step 5 below.</p>

<p>For example, the Service Provider generates a Single-Use Token <code>37bb49b4</code> and a corresponding Token Secret <code>d0e46c19</code>, and returns the following as the body of the response:</p>

<pre><code>  token=37bb49b4
  secret=d0e46c19
</code></pre>

<h4>3. The Consumer Redirects the User to the Service Provider</h4>

<p>In order for the Consumer to be able to exchange the pre-obtained Single-Use Token for a Multi-Use Token, the Consumer MUST obtain approval from the User by directing the User to the Service Provider. The Consumer constructs an HTTP GET request to the Service Provider's Authorization Endpoint URL which will be sent via the User's web browser.</p>

<p>This request contains the following parameters:</p>

<ul>
<li><code>oauth_consumer_key</code>
: The Consumer Key </li>
<li><code>oauth_token</code>
: The Single-Use Token obtained in the previous step.</li>
<li>Any additional parameters, as defined by the Service Provider.</li>
</ul>

<p>Once the request URL has been generated the Consumer directs the User to the URL.</p>

<p>For example, if the Consumer requests the User to authorize a Single-Use Token at the Service Provider's Authorization Endpoint URL <code>https://sp.example.com/oauth/authorize</code> with the Consumer Key <code>0685bd91</code> and pre-obtained Single-Use Token <code>37bb49b4</code>, the request would be as follows:</p>

<pre><code>https://sp.example.com/oauth/authorize?oauth_consumer_key=0685bd91&amp;oauth_token=37bb49b4
</code></pre>

<h4>4. The Service Provider Authenticates the User and Obtains Consent</h4>

<p>The Service Provider verifies the User's identity and asks for consent as detailed in the "User Authentication and Consumer Access Grants" section.</p>

<h4>5. The Service Provider Directs the User Back to the Consumer</h4>

<p>The Service Provider instructs the User to inform the Consumer that authorization has completed.</p>

<h3>Manual-Token-Entry Consumers</h3>

<p>Manual-token-entry Consumers cannot redirect the User to the Service Provider nor accept incoming HTTP(S) requests from the Service Provider. Instead, A Single-Use Token and Token Secret will be generated by the Service Provider and presented to the User. The Consumer waits for the User to manually submit the Token and Token Secret back to it.</p>

<ol>
<li>The Consumer directs the User to request authorization</li>
<li>The Service Provider authenticates the User and obtains consent</li>
<li>The Service Provider presents a Single-Use Token and Token Secret to the User</li>
<li>The User enters the Single-Use Token and Token Secret in the Consumer</li>
</ol>

<p>Note: If a Service Provider knows a Consumer to be running on a mobile device or set-top box, the Service Provider SHOULD ensure that the Authorization Endpoint URL, the Single-Use Token, and Token Secret are short and simple for manual entry.</p>

<p><img src="./diagrams/oauth_oob_flow.png" alt="Manual-Token-Entry Provider Flow Diagram" /></p>

<h4>1. The Consumer directs the User to request authorization</h4>

<p>The Consumer directs the User to the Service Provider's Authorization Endpoint URL.</p>

<p>For example, the Consumer is requesting a Single-Use Token and Token Secret from the Service Provider's Authorization Endpoint URL <code>https://sp.example.com/oauth/authorize</code> with the Consumer Key <code>0685bd91</code>.</p>

<pre><code>  https://sp.example.com/oauth/authorize?oauth_consumer_key=0685bd91
</code></pre>

<h4>2. The Service Provider Authenticates the User and Obtains Consent</h4>

<p>The Service Provider verifies the User's identity and asks for consent as detailed in the "User Authentication and Consumer Access Grants" section.</p>

<h4>3. The Service Provider presents a Single-Use Token and Token Secret to the User</h4>

<p>The Service Provider presents the Single-Use Token and Token Secret to the User by displaying it on the screen or other available methods.</p>

<h4>4. The User Enters the Single-Use Token and Token Secret in the Consumer</h4>

<p>The User manually enters the Single-Use Token and Token Secret in the Consumer. This can be done by manually typing the information or using cut-and-paste.</p>

<h2>Obtaining a Multi-Use Token</h2>

<p>Obtaining a Multi-Use Token follows the same process for all Consumer types.</p>

<ol>
<li>Consumer Requests Multi-Use Token</li>
<li>Service Provider Grants Multi-Use Token</li>
<li>Consumer Accesses Service Provider API Endpoints</li>
</ol>

<h3>1. Consumer Requests Multi-Use Token</h3>

<p>The Single-Use Token and Token Secret MUST be exchanged for a Multi-Use Token and Token Secret.</p>

<p>To request a Multi-Use Token, the Consumer makes an HTTP request to an API Endpoint URL for Token exchange as specified by the Service Provider's documentation. The Service Provider documentation MUST specify either HTTP GET or POST for this endpoint. It is RECOMMENDED that this be a POST request. The request MUST be signed with the Single-Use Token Secret per "Signing API Requests".</p>

<p>The request contains the following parameters:</p>

<ul>
<li><code>oauth_consumer_key</code>
: The Consumer Key.</li>
<li><code>oauth_token</code>
: The Single-Use Token obtained previously.</li>
<li><code>oauth_nonce</code>
: A one-time use value to verify the request has not been made before. See the "Request Nonce" section. </li>
<li><code>oauth_ts</code>
: An integer representing the time of request, expressed in number of seconds after January 1, 1970 00:00:00 GMT.</li>
<li><code>oauth_sigalg</code>
: The signature algorithm that the Consumer used to sign the request. </li>
<li><code>oauth_sig</code>
: The signature as defined in "Signing API Requests".</li>
</ul>

<h3>2. Service Provider Grants Multi-Use Token</h3>

<p>The Service Provider exchanges the Consumer's Single-Use for a new Multi-Use Token and Token Secret. The Service Provider MUST verify that:</p>

<ul>
<li>The request is properly signed.</li>
<li>The Single-Use Token has not been exchanged before for a Multi-Use Token.</li>
<li>The Single-Use Token matches the Consumer Key.</li>
</ul>

<p>On successful verification, the Service Provider returns a Multi-Use Token and a Token Secret in the body of the response as newline separated name-value pairs, followed by any additional data as defined by the Service Provider's documentation.</p>

<p>For example:</p>

<pre><code>token=37bb49b4
secret=d0e46c19
</code></pre>

<p>The Multi-Use Token and Token Secret are stored by the Consumer to use when signing future API requests.</p>

<p>If the request is unsuccessful, the Service Provider MUST respond with an HTTP 401 Not Authorized, and MAY include some further details about why the request was not authorized.</p>

<h3>3. Consumer Accesses Service Provider API Endpoints</h3>

<p>After receiving the Multi-Use Token and Token Secret, the Consumer is able to use the Multi-Use Token and Token Secret to access the Protected Resources on behalf of the User. The Service Provider documentation MAY specify limitations on the Multi-Use Token such as expiration or other constrains.</p>

<p>The request contains the following parameters:</p>

<ul>
<li><code>oauth_consumer_key</code>
: The Consumer Key.</li>
<li><code>oauth_token</code>
: The Multi-Use Token.</li>
<li><code>oauth_nonce</code>
: A one-time use value to verify the request has not been made before. See the "Request Nonce" section. </li>
<li><code>oauth_ts</code>
: An integer representing the time of request, expressed in number of seconds after January 1, 1970 00:00:00 GMT.</li>
<li><code>oauth_sigalg</code>
: The signature algorithm that the Consumer used to sign the request. </li>
<li><code>oauth_sig</code>
: The signature as defined in "Signing API Requests". </li>
</ul>

<h2>Signing API Requests</h2>

<p>All API Endpoint URL requests MUST be signed by the Consumer and the signature verified by the Service Provider. Both the Consumer and Service Provider follow the same process to generate the request signature. The Consumer generates a signature and includes it with the request using the <code>oauth_sig</code> parameter, while the Service Provider generates a signature and compares it to the signature provided by the Consumer. The signature process includes the following steps:</p>

<ol>
<li>Normalize Service Provider request parameters</li>
<li>Concatenate parameters into a string</li>
<li>Sign or hash the concatenated parameters string</li>
</ol>

<p>The signature process MUST NOT change the request parameter names or values. It is a read-only process on the request. All request parameters MUST have be properly encoded as described in "HTTP Request Parameters" prior to applying the signature process.</p>

<h3>1. Normalize Service Provider Request Parameters</h3>

<p>All Service Provider request parameters starting with something other than <code>oauth_</code> SHALL be normalized as follows into a single string:</p>

<ol>
<li>Parameters are sorted by name, using lexicographical byte value ordering. If two or more parameters share the same name, they are sorted by their value. For example: <code>a=1</code>, <code>c=hi%20there</code>, <code>f=25</code>, <code>f=50</code>, <code>z=10</code>.</li>
<li>Parameters are concatenated in their sorted order into a single string. For each parameter, the name is separated from the corresponding value by an = character (ASCII code 61). Each name-value pair is separated by an <code>&amp;</code> character (ASCII code 38). For example: <code>a=1&amp;c=hi%20there&amp;f=25&amp;f=50&amp;z=10</code></li>
<li>The concatenated string is encoded as described in "HTTP Request Parameters".</li>
</ol>

<h3>2. Concatenate Parameters into a String</h3>

<p>The OAuth request parameters, custom request parameters, and the request properties are concatenated into a single string used as input to the signature algorithm. The request parameters MUST be concatenated in the following order:</p>

<ol>
<li><code>oauth_consumer_secret</code>
: The Consumer Secret.</li>
<li><code>oauth_consumer_key</code>
: The Consumer Key.</li>
<li><code>oauth_token</code>
: The Single-Use or Multi-Use Token.</li>
<li><code>oauth_token_secret</code>
: The Token Secret.</li>
<li><code>http_request_method</code>
: The HTTP request method used to send the request. Value MUST be uppercase, for example: <code>HEAD</code>, <code>GET</code>, <code>POST</code>, etc.</li>
<li><code>http_request_uri</code>
: The API Endpoint URL as defined in "Endpoint URLs".</li>
<li><code>normalized_request_parameters</code>
: The result string from step 1.</li>
<li><code>oauth_nonce</code>
: The request nonce.</li>
<li><code>oauth_ts</code>
: An integer representing the time of request, expressed in number of seconds after January 1, 1970 00:00:00 GMT.</li>
</ol>

<p>The above request parameters are concatenated in order into a single string. For each parameter, the name is separated from the corresponding value by an = character (ASCII code 61). Each name-value pair is seperated by an <code>&amp;</code> character (ASCII code 38).</p>

<h3>3. Sign or Hash the Concatenated String</h3>

<p>The concatenated string from step 3 (<code>concatenated_string</code>) is signed or hashed according to the chosen signature algorithm (indicated with the <code>oauth_sigalg</code> parameter):</p>

<ul>
<li><code>oauth_sig=md5</code>
: md5(concatenated_string)</li>
<li><code>oauth_sig=sha1</code>
: sha1(concatenated_string)</li>
<li><code>oauth_sig=hmac_sha256</code>
: hmac_sha256(oauth_consumer_secret, concatenated_string)</li>
<li><code>oauth_sig=openssl_x509_sign</code>
: openssl_x509_sign(private_certificate, concatenated_string). In the case of using x509 certs, the Service Provider would have the Consumer's public key and therefore would provide an empty string as the secret.</li>
</ul>

<h3>Example</h3>

<ol>
<li>Fetch the 3rd page of friends updates from Twitter for user <code>123456</code></li>
<li><p>The basic API request looks like so:</p>

<p><code>http://twitter.com/statuses/with_friends/123456.json?page=3&amp;count=50</code></p></li>
<li><p>Assuming the use of the <code>sha1</code> signature method and the following values:</p>

<ul>
<li><code>oauth_consumer_secret</code> => <code>3a2cd35</code></li>
<li><code>oauth_consumer_key</code> => <code>0685bd91</code></li>
<li><code>oauth_token</code> => <code>540ad18</code></li>
<li><code>oauth_token_secret</code> => <code>x2s55k0</code></li>
<li><code>oauth_nonce</code> => <code>MTgzNTYxODk4Mw</code></li>
<li><p><code>oauth_ts</code> => <code>1185517832</code></p>

<p><code>oauth_sig = sha1("oauth_consumer_secret=3a2cd35&amp;oauth_consumer_key=0685bd91&amp;oauth_token=540ad18&amp;oauth_token_secret=x2s55k0&amp;http_request_method=GET&amp;http_request_uri=http%3A%2F%2Ftwitter.com%2Fstatuses%2Ffriends/123456.json&amp;normalized_request_parameters=count%3D50%26page%3D3&amp;oauth_nonce=MTgzNTYxODk4Mw&amp;oauth_ts=1185517832")</code></p></li>
</ul></li>
<li><p>We need to pass to the server (in cleartext) the Consumer Key (<code>oauth_consumer_key</code>), the Token (<code>oauth_token</code>), the timestamp (<code>oauth_ts</code>), the nonce (<code>oauth_nonce</code>), the signature algorithm (oauth_sigalg), and the signed request (<code>oauth_sig</code>).
Consumers MUST NOT send any of the secrets with the request, since doing so would compromise the entire request, as well as subsequent requests.</p></li>
<li><p>The full signed request is then:</p>

<p><code>GET http://twitter.com/statuses/friends/123456.json?page=3&amp;count=50&amp;oauth_key=0685bd91&amp;oauth_token=540ad18&amp;oauth_nonce=MTgzNTYxODk4Mw&amp;oauth_ts=1181537927&amp;oauth_sigalg=sha1&amp;oauth_sig=2d047740b53ae16f670750bef5bb5c2a0f398f30</code></p></li>
</ol>

<h2>Request Nonce</h2>

<p>A nonce is a random string, uniquely generated for each request. The nonce allows the Service Provider to verify that a request has never been made before and helps prevent against replay attacks. More information about nonces can be found on Wikipedia (http://en.wikipedia.org/wiki/Cryptographic_nonce).</p>

<h2>Using HTTP-Authorization Headers</h2>

<p>This section defines an RFC 2617 extension to support OAuth. It uses the standard HTTP Authorization and WWW-Authenticate headers to pass credentials rather than using URL parameters. All Consumers SHOULD be able to supply an OAuth Authorization header as an alternative to passing URL parameters. It is RECOMMENDED that Service Providers accept such a header, and such Service Providers MUST signal Consumers by returning the OAuth WWW-Authenticate header upon all requests for the Protected Resources. For the remainder of this section, we assume that the Service Provider under discussion has chosen to support this extension.</p>

<p>When using an HTTP-Authorization header, the OAuth request parameters are not included in the request URL. Rather they are included as the value of the header.</p>

<pre><code>`Authorization: OAuth oauth_token="540ad18" oauth_key="0685bd91" oauth_nonce="MTgzNTYxODk4Mw" oauth_ts="1185517832" oauth_sigalg="SHA1" oauth_sig="2d047740b53ae16f670750bef5bb5c2a0f398f30"`
</code></pre>

<p>To reject a request that lacks appropriate credentials, the Service Provider MUST respond with a 401 Unauthorized response. Such a response MUST include at least one OAuth WWW-Authenticate header and MAY include additional WWW-Authenticate headers:</p>

<pre><code>`401 Unauthorized`
...
`WWW-Authenticate: OAuth realm="https://sp.example.com/oauth/authorize?res=74637288"`
</code></pre>

<p>The realm parameter both defines a protection realm per RFC 2617, section 1.2, and also specifies the Authorization Endpoint URL to be used by the Consumer to obtain authorization for the accessed resource.</p>

<p>A Consumer MAY also include an empty, token-less OAuth Authorization header on any HTTP request to inform a Service Provider that it supports OAuth. The Service Provider MUST then respond with the appropriate WWW-Authenticate header for the requested resource in the response. For example, a Consumer could inquire using HEAD and then adjust its UI if the Service Provider supports OAuth.</p>

<h2>Error Messages</h2>

<ul>
<li>HTTP 400 Bad Request

<ul>
<li>Invalid Timestamp</li>
<li>Unsupported Signature Algorithm</li>
</ul></li>
<li>HTTP 401 Unauthorized

<ul>
<li>Invalid Consumer Key</li>
<li>Invalid/Expired Token</li>
<li>Invalid Signature</li>
<li>Nonce Spent</li>
</ul></li>
</ul>

<h2>Security Considerations</h2>

<ul>
<li>Service Providers are RECOMMENDED to use HTTPS for endpoints URLs which contain sensitive information such as Token Secrets. The decision to use HTTPS is left for each Service Provider.</li>
<li>Credentials as GET parameters can get logged in various places</li>
<li>Timestamps SHOULD be good for 5 minutes, this gives sufficient time to deal with network latency, without becoming a security hole, or placing an unbearable burden on the server for tracking and storing nonces. Ideally, servers would provide a method for retrieving what they think the current time is.</li>
</ul>
</body>
</html>